Apple WWDC 1996/WWDC96_1996 (CD).toast/Technology Materials/MacOS 8 Resources/Developer Tools/Mac OS 8 Interfaces & Libraries/Interfaces/IDLIncludes/HIObjects.idl

Text File | 1996-05-01 | 12.6 KB | 376 lines | [TEXT/MPS ]

/*
     File:        HIObjects.idl

     Contains:    Interface for the base class of all HI toolbox elements.

     Version:    Technology:    System 8.0
                 Release:    Universal Interfaces 3.0d3 on Copland DR1

     Copyright:    © 1995-1996 by Apple Computer, Inc.  All rights reserved.

     Bugs?:        If you find a problem with this file, send the file and version
                 information (from above) and the problem description to:

                     Internet:    [e-mail]
                     AppleLink:    APPLE.BUGS
*/


#ifndef __HIOBJECTS_IDL__
#define __HIOBJECTS_IDL__

#include <somobj.idl>
#include <somcls.idl>

#include <Types.idl>
#include <Dialogs.idl>
#include <Collections.idl>
#include <Quickdraw.idl>
#include <TextObjects.idl>
#include <AppleEvents.idl>
#include <Events.idl>
#include <Resources.idl>

#include <HIImagingObjects.idl>
#include <HIObjectTypes.idl>


interface HIWindow;

/* ########################################################################

    HIObject

        the base Toolbox object class

   ######################################################################## */
interface HIObject : SOMObject
{
// ======================================================
// Attributes
// ======================================================
    HIWindow            GetWindow();
    CGrafPtr            GetPort();
    void                GetRefLabel(out RefLabel identifier);
    Collection            GetCollection();


// ======================================================
// Public Methods
// ======================================================

// • initialization / disposal •
    // programatically initialize the object
    OSStatus Init (in RefLabel identifier, in Rect boundingRect);

    // dispose any dynamically allocated fields.
    void Terminate ();

    // for refcount management
    HIObject Clone ();
    void Release ();
    ItemCount GetOwnerCount();

    // Initialize the object from the data encapsulated in the given AppleEvent.
    // baseInitializerData contains the data for the entire object
    // initializerDataForClass contains the AESubDesc that points to
    // the data for the current class; and should be bumped down
    // to the subClass's initializer on exit.
    OSStatus InitFromAERecord (in AESubDesc baseInitializerData,
        in AESubDesc initializerDataForClass,
        in HIAERecordDataFormat dataFormat);

    // Dump the object's state and initialization data in a format
    // that can be read by InitFromData.
    OSStatus WriteToAERecord (in AERecord dataForSubclass,
            in AERecord objectData, in HIAERecordDataFormat dataFormat);

// • location •
    // Calculate the optimal size of the object - this
    // is the smallest rect that can completely enclose
    // the object's content.
    void CalculateOptimalSize (out SInt16 optimalWidth, out SInt16 optimalHeight);

    // Manipulate the bounding rect for the object
    void GetBoundingRect (in HICoordinateSystem coordinate, out Rect boundingRect);
    void SetBoundingRect (in HICoordinateSystem coordinate, in Rect newBoundingRect);

    // other ways to change the bounding rect.  Note that
    // SetPosition can be optimized since there is no resizing involved.
    void SetPosition (in HICoordinateSystem coordinate, in Point newPosition);
    void SetSize (in SInt16 width, in SInt16 height);

    // Get the rect in which an object draws itself.  This
    // may be bigger than the bounding rect, as it includes
    // keyboard focus ring, default ring, etc.
    void GetUpdateRect (in HICoordinateSystem coordinate, out Rect updateRect);

// • Enabling •
    // If enabled, an object should accept clicks.
    void Enable();
    void Disable();
    boolean IsEnabled ();

// • Visibility •
    void Show();
    void Hide();
    boolean IsVisible ();

// • Event Handling •

    // All event handling methods return the following OSStatus values:
    //        noErr: event handled by the object.  Don't pass through.
    //        errAEEventNotHandled: event not handled by object.  Pass through
    //            to other interested objects, and eventually back to event handler.
    //        (other error value): some kind of failure handling the event.
    OSStatus HandleAppleEvent (in AEEventClass eventClass, in AEEventID eventID,
            in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

    OSStatus HandleActivate (in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);
    OSStatus HandleDeactivate (in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

    // handle a navigational key event
    OSStatus HandleNavigation (in SInt8 key, in SInt8 keyCode,             /* ••• shouldn't be key based. What is real namespace of params?  */
        in EventModifiers modifiers, in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);


    // react to a click in the object's bounding area.
    // See event handling note above for info on return values
    OSStatus HandleMouseDownInContent (in Point portLocalWhere, in EventModifiers modifiers,
        in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

    // mouse has moved.  return true if the object still wants
    // to be informed when the mouse has moved or been released.
    OSStatus HandleMouseMovedInContent (in Point portLocalWhere, in EventModifiers modifiers,
        in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

    // mouse has stopped moving
    OSStatus HandleMouseStoppedMovingInContent (in Point portLocalWhere, in EventModifiers modifiers,
        in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

    // mouse button has been released since it has been clicked inside the object.
    // return true if the object accepted the click.
    OSStatus HandleMouseUpInContent (in Point portLocalWhere, in EventModifiers modifiers,
        in AppleEvent theEvent, in AppleEvent reply, in AEHandlerTableRef handlerTableRef);

// • UserInputFocus •
    // give (or take away) focus to the object.
    // it is the client's responsibility to keep track
    // of which object has focus.
    void TakeUserInputFocus();
    void ReleaseUserInputFocus();
    boolean HasUserInputFocus();

    // query for user input focus.  Return true if the
    // object is in a state where it can give up
    // user input focus.
    boolean CanReleaseUserInputFocus ();

    // manipulate flags affecting an object's ability to accept focus.
    void SetUserInputFocusFlags(in HIUserInputFocusFlags flags);
    HIUserInputFocusFlags GetUserInputFocusFlags();

// • Title •
    // the title is an imaging object (usually a piece of text, but
    // it could be something else like a picture or icon).  By
    // default, a panel has no title.
    OSStatus SetTitle(in ConstHIImageRef title, in HIAdoptionFlags disposalAdoptionFlags);
    OSStatus GetTitle(out HIImageRef title);


// • Imaging •

    // while an object must live in a window, it can be drawn in any
    // port, to simplify printing.  If whichPort is set to NULL,
    // than we assume we're drawing in our window.
    // if drawRgn is NULL, then draw the entire object; otherwise, attempt
    // to draw only the content that lies in the region.

    // This method should NOT be overridden - to change how your
    // object appears, override DrawContent.
    void Draw (in CGrafPtr whichPort, in RgnHandle drawRgn);

    // This method should NOT be overridden - to change how your
    // object erases, override EraseContent.

    void Erase (in CGrafPtr whichPort, in RgnHandle eraseRgn);

    // Force a redraw of the object.  Based on the value of
    // the object's fDrawingMode, the redraw will happen
    // either (i) immediately, (ii) next update event, or
    // (iii) some time later when the mode is changed to
    // one of the first two values.
    void Invalidate ();

    // set the object's drawing mode - the default behavior
    // is for the object to draw next update event
    HIDrawingMode GetDrawingMode ();
    void SetDrawingMode (in HIDrawingMode drawingMode);

    void SetBackgroundPattern (in PixPatHandle backgroundPattern);
    PixPatHandle GetBackgroundPattern();


// • Clipboard •
    // fClipboardSupportFlags indicates when it makes sense for
    // an object to use cut, copy, paste, clear or undo
    // functionality.  They can be changed at any time
    // during the object's lifetime.
    void Cut ();
    void Copy ();
    void Paste ();
    void Clear ();
    HIClipboardSupportFlags    GetClipboardSupportFlags();

// • State Change
    OSStatus            AddStateChangeCallback (in HIStateChangeCallbackProcPtr changedStateCallback, out HIStateChangeCallbackRef newCallbackRef);
    OSStatus            RemoveStateChangeCallback (in HIStateChangeCallbackRef callbackRefToRemove);

// ======================================================
// Procedural calls
//     These are not object methods, but rather static functions
// ======================================================


// Returns all Panels in the current process with a matching RefLabel
    OSStatus        GetHIObjectFromRefLabel(in RefLabel identifier, in ItemCount requestedObjects,
                                                out ItemCount totalObjects, inout HIObject theObjects);

// create and initialize an HI Object
// whose data is encapsulated in the given AESubdesc or resource
    OSStatus         GetNewHIObject (in AESubDesc objectInitializer, out HIObject newObject);
    OSStatus         GetNewHIObjectFromResource (in ResID objectInitializerResourceID, out HIObject newObject);

// ======================================================
// Protected Methods
//     Call these methods only from within object implementation!
// ======================================================
    // actually draw yourself
    void DrawContent (in CGrafPtr whichPort, in RgnHandle drawRgn);

    // erase the object.  by default, this will erase the entire
    // bounding rect.  Override if your shape is unusual and
    // you want to erase only the area where you typically draw
    void EraseContent (in CGrafPtr whichPort, in RgnHandle regionToErase);

    // transfer the given point from Port coordinates
    // to coordinates local to this object's location,
    // or vice versa.
    void TranslatePoint (in HICoordinateSystem translateFrom,
                         in HICoordinateSystem translateTo,
                         in Point sourcePoint,
                         out Point translatedPoint);

    // similar to TranslatePoint, but translates a rectangle
    void TranslateRect  (in HICoordinateSystem translateFrom,
                         in HICoordinateSystem translateTo,
                         in Rect sourceRect,
                         out Rect translatedRect);

    // State has changed.  Call this utility method
    // to call through to the list of state changed procs, if any
    void StateChanged (in HIStateChangeCodeCreator selectorCreator, in HIStateChangeCode changedCode);

    void SetClipboardSupportFlags(in HIClipboardSupportFlags flags);

    // Verify the object's internal state, for qualification
    // should be overridden by subclasses to verify
    // their own fields, too.  In optimized builds, this should
    // do nothing and return noErr.
    OSStatus Verify ();

    implementation {

        passthru C_h =     "#include <Types.h>"
                        "#include <Quickdraw.h>"
                        "#include <TextObjects.h>"
                        "#include <Drag.h>"
                        "#include <Collections.h>"
                        "#include <HIImagingObjects.h>"
                        "#include <HIObjectTypes.h>";

        passthru C_xh = "#include <Types.h>"
                        "#include <Quickdraw.h>"
                        "#include <TextObjects.h>"
                        "#include <Drag.h>"
                        "#include <Collections.h>"
                        "#include <HIImagingObjects.xh>"
                        "#include <HIObjectTypes.h>";

        GetHIObjectFromRefLabel:    procedure, noself;
        GetNewHIObject:                procedure, noself;
        GetNewHIObjectFromResource:    procedure, noself;

        Clone:                        nooverride;
        Release:                    nooverride;
        GetOwnercount:                nooverride;

        releaseorder:    GetWindow,
                        GetPort,
                        GetRefLabel,
                        GetCollection,
                        AddStateChangeCallback,
                        RemoveStateChangeCallback,
                        SetBackgroundPattern,
                        GetBackgroundPattern,
                        Init,
                        Terminate,
                        InitFromAERecord,
                        WriteToAERecord,
                        CalculateOptimalSize,
                        GetBoundingRect,
                        SetBoundingRect,
                        SetPosition,
                        SetSize,
                        GetUpdateRect,
                        Enable,
                        Disable,
                        IsEnabled,
                        Show,
                        Hide,
                        IsVisible,
                        HandleAppleEvent,
                        HandleActivate,
                        HandleDeactivate,
                        HandleNavigation,
                        HandleMouseDownInContent,
                        HandleMouseUpInContent,
                        HandleMouseMovedInContent,
                        HandleMouseStoppedMovingInContent,
                        TakeUserInputFocus,
                        ReleaseUserInputFocus,
                        HasUserInputFocus,
                        CanReleaseUserInputFocus,
                        SetUserInputFocusFlags,
                        GetUserInputFocusFlags,
                        SetTitle,
                        GetTitle,
                        Draw,
                        Erase,
                        Invalidate,
                        GetDrawingMode,
                        SetDrawingMode,
                        Cut,
                        Copy,
                        Paste,
                        Clear,
                        SetClipboardSupportFlags,
                        GetClipboardSupportFlags,
                        DrawContent,
                        EraseContent,
                        TranslatePoint,
                        TranslateRect,
                        StateChanged,
                        Verify,
                        GetHIObjectFromRefLabel,
                        GetNewHIObject,
                        GetNewHIObjectFromResource,
                        Clone,
                        Release,
                        GetOwnerCount;

    };
};

#endif